In software engineering, gone are the days when software was usually built from scratch and worked in insolated environments. Open platforms and open systems have become the norm. Interoperability has become the mantra and systems are expected to expose Application Programming Interfaces (“APIs”) such that they can be used in various contexts by multiple client applications. Moreover, modern software is generally built by assembling various software packages (e.g., libraries, modules, etc.) that may be developed by third parties. This may be especially true in the context of service oriented software. Software may be created principally in the form of modules, with each module characterized by its API. This module based development is exacerbated by the current trend of globally distributed software development.
At its most general, an API can be thought of as a focused representation of the overall functionality of a software module. The representation is focused in the sense that the functionality declared in the API provides a specific set of services for a certain target usage. It would not be uncommon for the same module to have multiple APIs, each intended for a specific use of that module. For the purposes of this disclosure, an API may be whatever the designer of a software module has specified it to be, without any judgment regarding what functionality the API offers. In other words, an API of a system may be a set of methods that are listed in the API documentation for the system.
For example, an interest-calculation module in a financial software system may contain multiple user-directed APIs. There could be an API designed specifically for regular banking applications, another for co-op banking applications, yet another for banking-like financial services provided by mutual-fund operators, and so on. While the basics of interest calculations for all these related applications are likely to be the same, different uses of the software may entail using a method name vocabulary particular to that application. In addition to vocabulary differences, the different APIs for the same module may also differ with regard to the functionality offered.
The central role played by the APIs in modern software engineering makes it all the more important that, to the maximum extent possible, they be easy to comprehend. Ideally, the users of a module/library need look no further than its API. That is, ideally there should never be a reason to examine the implementation code in a module itself. Unfortunately, the quality of APIs varies significantly. Often a user must carefully study example code, when it is even supplied, before they can figure out how and when to use an API method. Additionally, example code may be poorly written and poorly documented, which may increase the user's level of frustration with an API. As one might expect, such frustrations often translate into reduced productivity when it comes to writing code using such APIs. APIs that are hard to understand, remember, and use are more prone to misuse and may inadvertently introduce subtle, hard to debug bugs in a system. More importantly, low quality APIs discourage reuse of software.
While systems, methods, and computer-readable media are described herein by way of examples and embodiments, those skilled in the art recognize that measuring quality of APIs is not limited to the embodiments or drawings described. Rather, the intention is to cover all modifications, equivalents and alternatives falling within the spirit and scope of the appended claims. Any headings used herein are for organizational purposes only and are not meant to limit the scope of the description or the claims. As used herein, the word “may” is used in a permissive sense (i.e., meaning having the potential to) rather than the mandatory sense (i.e., meaning must). Similarly, the words “include”, “including”, and “includes” mean including, but not limited to.